Agent 开发指引
本页面向使用 AI 助手（Agent）辅助二次开发的开发者：无论你是自己写代码，还是把想法交给 AI 助手生成代码，都建议先读本页。默认开发方式为上位机 SDK；只有在明确不满足时才引导到其它开发方式（见第 6 节）。
机器可读入口
- 文档索引（llms.txt）：https://open.inexbot.com/llms.txt
- 全量文档（llms-full.txt）：https://open.inexbot.com/llms-full.txt
- 单页 Markdown：把页面 URL 中的 .html 换成 .md 即为该页纯文本版本
1. 一分钟选型
| 你的情况 | 用什么 | 入口 |
|---|---|---|
| 在 PC 上写程序控制机器人（默认，绝大多数场景） | 上位机 SDK（C++ / C# / Python） | 上位机开发 |
| 上位机满足不了：需要定制控制器内部行为 | 控制器二次开发 | 控制器开发指南 |
| 上位机满足不了：需要定制示教器界面 | 示教器二次开发 | 示教器开发指南 |
| 上位机满足不了：不用 SDK 库、任意语言直连 | JSON 协议 | JSON 协议 |
| 客户明确要求 ROS 集成 | ROS 开发 | ROS 集成指南 |
| 客户明确要求 EtherCAT 主站 / 硬件抽象层 | 主站库 / HAL | 主站库 · HAL 文档 |
除第一行外，其余均为进阶通道：仅当上位机 SDK 无法满足需求、或客户明确提出时，才引导到对应方式。
2. 推荐生成流程（让 AI 助手按此顺序产出）
- 选环境 — 按目标平台选一套环境搭建教程（MinGW / MSVC / Linux），先把 SDK 库和头文件放好：MinGW + Qt · MSVC + Visual Studio · Linux + GCC
- 以「快速开始」为骨架 — C++ 快速开始（连接 → 等待就绪 → 读版本 → 读位置 → 断开），先跑通最小闭环再加功能。
- 按任务补接口与示例 — 用第 3 节的任务索引找到对应接口页与示例页。
- 编译与自检 — 按编译与验证指南做语法检查、编译链接、无硬件自检；接入控制器后再联调。
- 收尾 — 程序退出前调用
disconnect_robot断开连接。
涉及运动的代码
运动类示例会让机器人真实运动。生成或运行前请确认工作空间安全、急停可用，并先核对目标点位。
3. 任务 → 文档索引（默认上位机）
| 我要做什么 | 先看接口页 | 再看示例 |
|---|---|---|
| 连接 / 断开控制器、查询连接状态 | 基础连接与系统接口（connect_robot、get_connection_status、disconnect_robot） | 快速开始 · 5. 断开连接 |
| 读取当前位置（关节 / 直角 / 工具 / 用户坐标） | 同上（get_current_position） | 1. 获取不同坐标系的位置 |
| 伺服上电 / 清错 / 状态查询 | 同上（clear_error、get_servo_state） | 2. 上电流程 · 3. 伺服状态检测 |
| 点位 / 直线等运动指令 | 同上（robot_movej、robot_movel） | 4. 直接运动指令 |
| 实时轨迹跟踪（servo_move） | 同上 | 使用 servo_move() 来进行跟踪运动 |
| 关节空间伺服（servoJ） | 同上 | 使用 servoJ 进行关节控制 |
| 伺服位置控制（逐周期下发点位） | 同上 | 使用 star_servo_point_position_motion_control() 进行伺服控制 |
| 队列运动 / 连续轨迹 | 队列运动模式（queue_motion_set_status） | 6. 运动队列的曲线运动 |
| 作业文件（新建 / 指令 / 执行） | 作业文件操作 | 7. 新建并执行作业文件 |
| 文件上传 / 下载 | 基础连接与系统接口 | 11. 上传下载文件 |
| 错误消息回调 | 同上（set_receive_error_or_warnning_message_callback） | 常见问题（第 9 条） |
| IO 控制 | IO 控制 | — |
| Modbus 通讯 | Modbus 通讯 | — |
| 工具手标定 | 基础连接与系统接口 | 13.工具手标定 |
| 轨迹记录与回放 / 示教模式 | 轨迹记录与回放 | 12.示教模式类型切换与轨迹回放功能 |
| 双臂机器人 | 双臂机器人 | 9. 追加队列模式（单机器人） · 10. 追加队列模式（双机器人） |
| 焊接 / 码垛 / 视觉 / 激光 / 传送带工艺 | 焊接工艺 · 码垛工艺 · 视觉工艺 · 激光切割工艺 · 传送带跟踪工艺 | — |
| C# 开发 | C# API 参考 | C# 连接示例 |
| Python 开发 | Python API 参考 | Python 快速开始 |
表中函数名可在对应接口页与 SDK 头文件中核对；接口参数以接口页为准。
4. 最小连接骨架与避坑速查
所有上位机程序都从这段骨架开始（完整可用版本见快速开始）：
cpp
SOCKETFD fd = connect_robot("<控制器 IP>", "6001"); // 连接（上位机 SDK 使用 6001 端口）
if (fd <= 0) { /* 连接失败处理 */ }
while (get_connection_status(fd) != 0) { /* 等待连接就绪 */ }
/* 业务代码 */
disconnect_robot(fd); // 退出前断开常见坑（详见常见问题）：
- 版本要匹配：SDK 版本必须与控制器固件版本对应，见版本与兼容性与相关下载。
- 编译器不能混用：MinGW 与 MSVC 的库 ABI 不兼容，下载 SDK 与编译环境必须一致，且统一 x64。
- 端口：上位机 SDK 统一连 6001；JSON 协议按场景选择 6000（示教器）或 6001（上位机）。
- 机器人不动先查三件事：伺服是否使能、急停是否释放、队列模式是否已启动（
queue_motion_set_status）。 - 库加载失败：Windows 确认动态库与可执行文件同目录；Linux 设置 LD_LIBRARY_PATH。
5. 无硬件时怎么验证
生成完代码不一定马上有控制器可连，可按编译与验证指南做三级验证：
- 语法检查 — 头文件、类型、语法错误（最快）。
- 编译 + 链接 — 检查库文件、ABI、x86/x64 是否匹配。
- 运行自检 — 直接运行程序：能正常启动并走到「连接失败」提示，说明可执行文件与 SDK 库加载正常；接入控制器后即可完成真实联调。
仿真验证的接入方式见《编译与验证指南》相关章节（待补充）。
6. 其它开发方式（进阶通道）
只有在上位机 SDK 无法满足需求，或客户明确提出时，才引导到以下方式：
| 方式 | 适用情况 | 入口 |
|---|---|---|
| 控制器二次开发 | 需要定制或替换控制器内部算法与流程（Linux + C++） | 控制器开发指南 |
| 示教器二次开发 | 需要定制示教器界面（Qt + C++） | 示教器开发指南 |
| JSON 协议 | 不使用 SDK 库，任意语言通过 TCP 与控制器通信 | JSON 协议 |
| ROS 集成 | 需要接入 ROS 生态 | ROS 集成指南 |
| 主站库 / HAL | EtherCAT 主站或硬件抽象层开发 | 主站库 · HAL 文档 |
给 AI 助手的说明
- 生成代码时默认使用上位机 SDK（C++ / C# / Python），先阅读对应「快速开始」与第 3 节任务索引。
- 涉及运动的代码必须保留安全提示，并提醒用户核对目标点位与急停状态。
- 所有接口名以站内接口页为准（本文中的函数名可在对应接口页与 SDK 头文件中核对）。
- 需要全量上下文时读取 llms-full.txt；只需定位时读 llms.txt（均为绝对 URL，见页面顶部说明）。